home *** CD-ROM | disk | FTP | other *** search
Text File | 1990-10-14 | 39.5 KB | 1,093 lines |
- Newsgroups: comp.sources.misc
- X-UNIX-From: dvadura@watdragon.waterloo.edu
- subject: v15i064: dmake version 3.6 (part 12/25)
- from: Dennis Vadura <dvadura@watdragon.waterloo.edu>
- Sender: allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc)
-
- Posting-number: Volume 15, Issue 64
- Submitted-by: Dennis Vadura <dvadura@watdragon.waterloo.edu>
- Archive-name: dmake-3.6/part12
-
- #!/bin/sh
- # this is part 12 of a multipart archive
- # do not concatenate these parts, unpack them in order with /bin/sh
- # file man/dmake.tf continued
- #
- CurArch=12
- if test ! -r s2_seq_.tmp
- then echo "Please unpack part 1 first!"
- exit 1; fi
- ( read Scheck
- if test "$Scheck" != $CurArch
- then echo "Please unpack part $Scheck next!"
- exit 1;
- else exit 0; fi
- ) < s2_seq_.tmp || exit 1
- echo "x - Continuing file man/dmake.tf"
- sed 's/^X//' << 'SHAR_EOF' >> man/dmake.tf
- Xto introduce options on command lines. On UNIX it's value is '-', on
- XMSDOS it's value may be '/' or '-'.
- XThe macro is internally defined and is not user setable.
- XThe MSDOS version of \fBdmake\fP attempts to first extract SWITCHAR from an
- Xenvironment variable of the same name. If that fails it then attempts to
- Xuse the undocumented getswitchar interrupt call, and returns the result of
- Xthat. Thus under MSDOS version 4.0 you must set the value of the environment
- Xmacro SWITCHAR to '/' to obtain predictable behaviour.
- X.PP
- XAll boolean macros currently understood by
- X.B dmake
- Xcorrespond directly to the previously defined attributes.
- XThese macros provide
- Xa second way to apply global attributes, and represent the
- Xpreferred method of doing so. They are used by assigning them a
- Xvalue. If the value is not a NULL string then the boolean condition
- Xis set to on.
- XIf the value is a NULL string then the condition is set to off.
- XThere are five conditions defined and they correspond directly to the
- Xattributes of the same name. Their meanings are defined in the ATTRIBUTES
- Xsection above.
- XThe macros are:
- X\&\fB.EPILOG\fP,
- X\&\fB.IGNORE\fP,
- X\&\fB.MKSARGS\fP,
- X\&\fB.PRECIOUS\fP,
- X\&\fB.PROLOG\fP,
- X\&\fB.SEQUENTIAL\fP,
- X\&\fB.SILENT\fP,
- X\&\fB.SWAP\fP, and
- X\&\fB.USESHELL\fP.
- XAssigning any of these a non NULL value will globally set
- Xthe corresponding attribute to on.
- X.SH "RUN_TIME MACROS"
- XThese macros are defined
- Xwhen \fBdmake\fP is making targets, and may take on different values for each
- Xtarget. \fB$@\fP is defined to be the full target name, \fB$?\fP is the
- Xlist of all out of date prerequisites, \fB$&\fP is the list of all
- Xprerequisites, \fB$>\fP is the name of the library if the current target is a
- Xlibrary member, and
- X\fB$<\fP is the list of prerequisites specified in the current rule.
- XIf the current target had a recipe inferred then \fB$<\fP is the name of the
- Xinferred prerequisite even if the target had a list of prerequisites supplied
- Xusing an explicit rule that did not provide a recipe. In such situations
- X\fB$&\fP gives the full list of prerequisites.
- X.PP
- X\fB$*\fP is defined as
- X\fB$(@:db)\fP when making targets with explicit recipes and is defined as the
- Xvalue of % when making targets whose recipe is the result of an inference.
- XIn the first case \fB$*\fP is the target name with no suffix,
- Xand in the second case, is the value of the matched % pattern from
- Xthe associated %-rule.
- X\fB$^\fP expands to the set of out of date prerequisites taken from the
- Xcurrent value of \fB$<\fP.
- XIn addition to these,
- X\fB$$\fP expands to $, \fB{{\fP expands to {, \fB}}\fP expands to }, and the
- Xstrings \fB<+\fP and \fB+>\fP are recognized
- Xas respectively starting and terminating a text diversion when they appear
- Xliterally together in the same input line.
- X.PP
- XThe difference between $? and $^ can best be illustrated by an example,
- Xconsider:
- X.RS
- X.sp
- X.nf
- Xfred.out : joe amy hello
- X\trules for making fred
- X
- Xfred.out : my.c your.h his.h her.h # more prerequisites
- X.fi
- X.sp
- X.RE
- XAssume joe, amy, and my.c are newer then fred.out. When
- X.B dmake
- Xexecutes the recipe for making fred.out the values of the following macros
- Xwill be:
- X.RS
- X.sp
- X.nf
- X.Is "$@ "
- X.Ii "$@"
- X--> fred.out
- X.Ii "$*"
- X--> fred
- X.Ii "$?"
- X--> joe amy my.c # note the difference between $? and $^
- X.Ii "$^"
- X--> joe amy
- X.Ii "$<"
- X--> joe amy hello
- X.Ii "$&"
- X--> joe amy hello my.c your.h his.h her.h
- X.fi
- X.sp
- X.RE
- X.SH "FUNCTION MACROS"
- XOnly one function macro is defined at this time. The $(mktmp ...) construct
- Xcan be used to create a temporary file containing data and returns the name
- Xof that file as it's result. See the TEXT DIVERSION section for details on
- Xits use. Temporary files created using this macro persist for the duration
- Xof the
- X.B dmake
- Xrun if processed as part of a macro assignment operation, or until an
- Xassociated target's recipe is fully completed at which time the temporary file
- Xis removed. NOTE: Specifying '-v' on the command line causes all temporary
- Xfiles to be retained when
- X.B dmake
- Xexits.
- X.SH "DYNAMIC PREREQUISITES"
- X.B dmake
- Xlooks for prerequisites whose names contain macro expansions during target
- Xprocessing. Any such prerequisites are expanded and the result of the
- Xexpansion is used as the prerequisite name. As an example the line:
- X.sp
- X\tfred : $$@.c
- X.sp
- Xcauses the $$@ to be expanded when \fBdmake\fP is making fred, and it resolves
- Xto the target \fIfred\fP.
- XThis enables dynamic prerequisites to be generated. The value
- Xof @ may be modified by any of the valid macro modifiers. So you can say for
- Xexample:
- X.sp
- X\tfred.out : $$(@:b).c
- X.sp
- Xwhere the $$(@:b) expands to \fIfred\fP.
- XNote the use of $$ instead of $ to indicate the dynamic expansion, this
- Xis due to the fact that the rule line is expanded when it is initially parsed,
- Xand $$ then returns $ which later triggers the dynamic prerequisite expansion.
- XIf you really want a $ to be part of a prerequisite name you must use $$$$.
- XDynamic macro expansion is performed in all user defined rules,
- Xand the special targets .SOURCE*, and .INCLUDEDIRS.
- X.SH "BINDING TARGETS"
- XThis operation takes a target name and binds it to an existing file, if
- Xpossible.
- X.B dmake
- Xmakes a distinction between the internal target name of a target and it's
- Xassociated external file name.
- XThus it is possible for a target's internal name and its external
- Xfile name to differ.
- XTo perform the binding, the following set of rules is used.
- XAssume that we are
- Xtrying to bind a target whose name is of the form \fIX.suff\fP,
- Xwhere \fI.suff\fP is the suffix and \fIX\fP is the stem portion
- X(ie. that part which contains the directory and the basename).
- X.B dmake
- Xtakes this target name and performs a series of search operations that try to
- Xfind a suitably named file in the external file system.
- XThe search operation is user controlled
- Xvia the settings of the various .SOURCE targets.
- X.RS
- X.IP 1.
- XIf target has the .SYMBOL attribute set then look for it in the library.
- XIf found, replace the target name with the library member name and continue
- Xwith step 2. If the name is not found then return.
- X.IP 2.
- XExtract the suffix portion (that following the `.') of the target name.
- XIf the suffix is not null, look up the special target .SOURCE.<suff>
- X(<suff> is the suffix).
- XIf the special target exists then search each directory given in
- Xthe .SOURCE.<suff> prerequisite list for the target.
- XIf the target's suffix was null (ie. \fI.suff\fP was empty) then
- Xperform the above search but use the special target .SOURCE.NULL instead.
- XIf at any point a match is found then terminate the search.
- XIf a directory in the prerequisite list is the special name `.NULL ' perform
- Xa search for the full target name without prepending any directory portion
- X(ie. prepend the NULL directory).
- X(a default target of '.SOURCE : .NULL' is defined by \fBdmake\fP at startup,
- Xand is user redefinable)
- X.IP 3.
- XThe search in step 2. failed. Repeat the same search but this time
- Xuse the special target .SOURCE.
- X.IP 4.
- XThe search in step 3. failed.
- XIf the target has the library member attribute (.LIBMEMBER)
- Xset then try to find the target in the library which was passed along
- Xwith the .LIBMEMBER attribute (see the MAKING LIBRARIES section).
- XThe bound file name assigned to a target which is successfully
- Xlocated in a library is the same name that would be assigned had the search
- Xfailed (see 5.).
- X.IP 5.
- XThe search failed. Either the target was not found in any of the search
- Xdirectories or no applicable .SOURCE special targets exist.
- XIf applicable .SOURCE special targets exist, but the target was not found,
- Xthen \fBdmake\fP assigns the first name searched as the bound file name.
- XIf no applicable .SOURCE special targets exist,
- Xthen the full original target name becomes the bound file name.
- X.RE
- X.PP
- XThere is potential here for a lot of search operations. The trick is to
- Xdefine .SOURCE.x special targets with short search lists and leave .SOURCE
- Xas short as possible.
- XThe search algorithm has the following useful side effect.
- XWhen a target having the .LIBMEMBER (library member) attribute is searched for,
- Xit is first searched for as an ordinary file.
- XWhen a number of library members require updating it is desirable to compile
- Xall of them first and to update the library at the end in a single operation.
- XIf one of the members does not compile and \fBdmake\fP stops, then
- Xthe user may fix the error and make again. \fBdmake\fP will not remake any
- Xof the targets whose object files have already been generated as long as
- Xnone of their prerequisite files have been modified as a result of the fix.
- X.PP
- XWhen defining .SOURCE and .SOURCE.x targets the construct
- X.sp
- X\t.SOURCE :
- X.br
- X\t.SOURCE : fred gery
- X.sp
- Xis equivalent to
- X.sp
- X\t.SOURCE :- fred gery
- X.PP
- X\fBdmake\fP correctly handles the UNIX Make variable VPATH. By definition VPATH
- Xcontains a list of ':' separated directories to search when looking for a
- Xtarget. \fBdmake\fP maps VPATH to the following special rule:
- X.sp
- X\t.SOURCE :^ $(VPATH:s/:/ /)
- X.sp
- XWhich takes the value of VPATH and sets .SOURCE to the same set of directories
- Xas specified in VPATH.
- X.SH "PERCENT(%) RULES AND MAKING INFERENCES"
- XWhen \fBdmake\fP makes a target it's set of prerequisites (if any)
- Xmust exist and the target must have a recipe which \fBdmake\fP
- Xcan use to make it.
- XIf the makefile does not specify an explicit recipe for the target then
- X.B dmake
- Xuses special rules to try to infer a recipe which it can use
- Xto make the target. Previous versions of Make perform this task by using
- Xrules that are defined by targets of the form .<suffix>.<suffix> and by
- Xusing the .SUFFIXES list of suffixes. The exact workings of this mechanism
- Xwere sometimes difficult to understand and often limiting in their usefulness.
- XInstead, \fBdmake\fP supports the concept of \fI%-meta\fP rules.
- XThe syntax and semantics of these rules differ from standard rule lines as
- Xfollows:
- X.sp
- X.nf
- X.RS
- X\fI<%-target>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<%-prerequisites>\fP] [;\fI<recipe>\fP]
- X.RE
- X.fi
- X.sp
- Xwhere \fI%-target\fP is a target containing exactly a single `%' sign,
- X.I attributes
- Xis a list (possibly empty) of attributes,
- X.I ruleop
- Xis the standard set of rule operators,
- X.I "%-prerequisites"
- X\&, if present, is a list of prerequisites containing zero or more `%' signs,
- Xand
- X.I recipe,
- Xif present, is the first line of the recipe.
- X.PP
- XThe
- X.I %-target
- Xdefines a pattern against which a target whose recipe is
- Xbeing inferred gets matched. The pattern match goes as follows: all chars are
- Xmatched exactly from left to right up to but not including the % sign in the
- Xpattern, % then matches the longest string from the actual target name
- Xnot ending in
- Xthe suffix given after the % sign in the pattern.
- XConsider the following examples:
- X.RS
- X.sp
- X.nf
- X.Is "dir/%.c "
- X.Ii "%.c"
- Xmatches fred.c but not joe.c.Z
- X.Ii "dir/%.c"
- Xmatches dir/fred.c but not dd/fred.c
- X.Ii "fred/%"
- Xmatches fred/joe.c but not f/joe.c
- X.Ii "%"
- Xmatches anything
- X.fi
- X.sp
- X.RE
- XIn each case the part of the target name that matched the % sign is retained
- Xand is substituted for any % signs in the prerequisite list of the %-meta rule
- Xwhen the rule is selected during inference and
- X.B dmake
- Xconstructs the dependency specified by the %-meta rule for the actual target.
- XAs an example the following %-meta rules describe the following:
- X.RS
- X.sp
- X%.c : %.y ; recipe...
- X.sp
- X.RE
- Xdescribes how to make any file ending in .c if a corresponding file ending
- Xin .y can be found.
- X.RS
- X.sp
- Xfoo%.o : fee%.k ; recipe...
- X.sp
- X.RE
- Xis used to describe how to make fooxxxx.o from feexxxx.k.
- X.RS
- X.sp
- X%.a :; recipe...
- X.sp
- X.RE
- Xdescribes how to make a file whose suffix is .a without inferring any
- Xprerequisites.
- X.RS
- X.sp
- X%.c : %.y yaccsrc/%.y ; recipe...
- X.sp
- X.RE
- Xis a short form for the construct:
- X.RS
- X.sp
- X%.c : %.y ; recipe...
- X.br
- X%.c : yaccsrc/%.y ; recipe...
- X.sp
- X.RE
- Xie. It is possible to specify the same recipe for two %-rules by giving
- Xmore than one prerequisite in the prerequisite list.
- XA more interesting example is:
- X.RS
- X.sp
- X% : RCS/%,v ; co $@
- X.sp
- X.RE
- Xwhich describes how to take any target and check it out of
- Xthe RCS directory if the corresponding file exists in the RCS directory.
- XThe equivalent SCCS rule would be:
- X.RS
- X.sp
- X% : s.% ; get $@
- X.sp
- X.RE
- X.PP
- XThe previous RCS example defines an infinite rule, because it says how to make
- X.I anything
- Xfrom RCS/%,v, and
- X.I anything
- Xalso includes RCS/fred.c,v.
- XTo limit the size of the graph that results from such rules
- X.B dmake
- Xuses the macro variable PREP (stands for % repetition). By default the value
- Xof this variable is 0, which says that no repetitions of a %-rule are to be
- Xgenerated. If it is set to something greater than 0, then that many
- Xrepetitions of any infinite %-rule are allowed. If in the above
- Xexample PREP was set to 1, then \fBdmake\fP would generate the dependency
- Xgraph:
- X.RS
- X.sp
- X% --> RCS/%,v --> RCS/RCS/%,v,v
- X.sp
- X.RE
- XWhere each link is assigned the same recipe as the first link.
- XPREP should be used only in special cases, since it may result in
- Xa large increase in the number of possible prerequisites tested.
- X.PP
- X.B dmake
- Xsupports dynamic prerequisite generation for prerequisites of %-meta rules.
- XThis is best illustrated by an example. The RCS rule shown above can infer
- Xhow to check out a file from a corresponding RCS file only if the target
- Xis a simple file name with no directory information. That is, the above rule
- Xcan infer how to find \fIRCS/fred.c,v\fP from the target \fIfred.c\fP,
- Xbut cannot infer how to find \fIsrcdir/RCS/fred.c,v\fP from \fIsrcdir/fred.c\fP
- Xbecause the above rule will cause \fBdmake\fP to look for RCS/srcdir/fred.c,v;
- Xwhich does not exist (assume that srcdir has it's own RCS directory as is the
- Xcommon case).
- X.PP
- XA more versatile formulation of the above RCS check out rule is the following:
- X.RS
- X.sp
- X% : $$(@:d)RCS/$$(@:f),v : co $@
- X.sp
- X.RE
- XThis rule uses the dynamic macro $@ to specify the prerequisite to try to
- Xinfer. During inference of this rule the macro $@ is set to the value of
- Xthe target of the %-meta rule and the appropriate prerequisite is generated by
- Xextracting the directory portion of the target name (if any), appending the
- Xstring \fIRCS/\fP to it, and appending the target file name with a trailing
- X\fI,v\fP attached to the previous result.
- X.PP
- X.B dmake
- Xcan also infer indirect prerequisites.
- XAn inferred target can have a list of prerequisites added that will not
- Xshow up in the value of $< but will show up in the value of $? and $&.
- XIndirect prerequisites are specified in an inference rule by quoting the
- Xprerequisite with single quotes. For example, if you had the explicit
- Xdependency:
- X.RS
- X.sp
- X.nf
- Xfred.o : fred.c ; rule to make fred.o
- Xfred.o : local.h
- X.fi
- X.sp
- X.RE
- Xthen this can be infered for fred.o from the following inference rule:
- X.RS
- X.sp
- X%.o : %.c 'local.h' ; rule to make a .o from a .c
- X.sp
- X.RE
- XYou may infer indirect prerequisites that are a function of the value of '%'
- Xin the current rule. The meta-rule:
- X.RS
- X.sp
- X%.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c
- X.sp
- X.RE
- Xinfers an indirect prerequisite found in the INC directory whose name is the
- Xsame as the expansion of $(INC), and the prerequisite name depends on the
- Xbase name of the current target.
- XThe set of indirect prerequisites is attached to the meta rule in which they
- Xare specified and are inferred only if the rule is used to infer a recipe
- Xfor a target. They do not play an active role in driving the inference
- Xalgorithm.
- XThe construct:
- X.RS
- X.sp
- X%.o : %.c %.f 'local.h'; recipe
- X.sp
- X.RE
- Xis equivalent to:
- X.RS
- X.sp
- X.nf
- X%.o : %.c 'local.h' : recipe
- X%.o : %.f 'local.h' : recipe
- X.fi
- X.sp
- X.RE
- X.PP
- XIf any of the attributes .SETDIR, .EPILOG, .PROLOG, .SILENT,
- X\&.USESHELL, .SWAP, .PRECIOUS, .LIBRARY, and .IGNORE
- Xare given for a %-rule then when that rule is bound to a target
- Xas the result of an inference, the target's set of attributes is augmented by
- Xthe attributes from the above set that are specified in the bound %-rule.
- XOther attributes specified for %-meta rules are not inherited by the target.
- XThe .SETDIR attribute is treated in a special way.
- XIf the target already had a .SETDIR attribute set and the bound %-rule also
- Xspecified a .SETDIR attribute then the one
- Xoriginally specified with the target prevails.
- XDuring inference any .SETDIR attributes for the inferred prerequisite
- Xare honored.
- XThe directories must exist for a %-meta rule to be selected as a possible
- Xinference path. If the directories do not exist no error message is issued,
- Xinstead the corresponding path in the inference graph is simply rejected.
- X.PP
- X.B dmake
- Xalso supports the old format special target .<suffix>.<suffix>
- Xby identifying any rules
- Xof this form and mapping them to the appropriate %-rule. So for example if
- Xan old makefile contains the construct:
- X.RS
- X.sp
- X\&.c.o :; cc -c $< -o $@
- X.sp
- X.RE
- X.B dmake
- Xmaps this into the following %-rule:
- X.RS
- X.sp
- X%.o : %.c; cc -c $< -o $@
- X.sp
- X.RE
- XFurthermore,
- X.B dmake
- Xunderstands several SYSV AUGMAKE special targets and maps them into
- Xcorresponding %-meta rules. These transformation must be enabled by providing
- Xthe -A flag on the command line or by setting the value of AUGMAKE to non
- XNULL.
- XThe construct
- X.RS
- X.sp
- X\&.suff :; recipe
- X.sp
- X.RE
- Xgets mapped into:
- X.RS
- X.sp
- X% : %.suff; recipe
- X.sp
- X.RE
- Xand the construct
- X.RS
- X.sp
- X\&.c~.o :; recipe
- X.sp
- X.RE
- Xgets mapped into:
- X.RS
- X.sp
- X%.o : s.%.c ; recipe
- X.sp
- X.RE
- XIn general, a special target of the form .<str>~ is replaced by the %-rule
- Xconstruct s.%.<str>, thereby providing support for the syntax used by SYSV
- XAUGMAKE for providing SCCS support.
- XWhen enabled, these mappings allow processing of existing SYSV
- Xmakefiles without modifications.
- X.PP
- X.B dmake
- Xbases all of it's inferences on the inference graph constructed from the
- X%-rules defined in the makefile.
- XIt knows exactly which targets can be made from which prerequisites by
- Xmaking queries on the inference graph. For this reason .SUFFIXES is not
- Xneeded and is completely ignored.
- X.PP
- XFor a %-meta rule to be inferred as the
- Xrule whose recipe will be used to make a target, the target's name must match
- Xthe %-target pattern, and any inferred %-prerequisite must already exist or
- Xhave an explicit recipe so that the prerequisite can be made.
- XWithout \fItransitive closure\fP on the inference graph the above rule
- Xdescribes precisely when an inference match terminates the search.
- XIf transitive closure is enabled (the usual case), and a prerequisite does
- Xnot exist or cannot be made, then
- X.B dmake
- Xinvokes the inference algorithm recursively on the prerequisite to see if
- Xthere is some way the prerequisite can be manufactured. For if the
- Xprerequisite can be made then the current target can also be made using the
- Xcurrent %-meta rule.
- XThis means that there is no longer a need to give a rule
- Xfor making a .o from a .y if you have already given a rule for making a .o
- Xfrom a .c and a .c from a .y. In such cases
- X.B dmake
- Xcan infer how to make the
- X\&.o from the .y via the intermediary .c and will remove the .c when the .o is
- Xmade. Transitive closure can be disabled by giving the -T switch on the
- Xcommand line.
- X.PP
- XA word of caution.
- X.B dmake
- Xbases its transitive closure on the %-meta rule targets.
- XWhen it performs transitive closure it infers how to make a target from a
- Xprerequisite by performing a pattern match as if the potential prerequisite
- Xwere a new target.
- XThe set of rules:
- X.RS
- X.nf
- X.sp
- X%.o : %.c :; rule for making .o from .c
- X%.c : %.y :; rule for making .c from .y
- X% : RCS/%,v :; check out of RCS file
- X.fi
- X.sp
- X.RE
- Xwill, by performing transitive closure, allow \fBdmake\fP to infer how to make
- Xa .o from a .y using a .c as an intermediate temporary file. Additionally
- Xit will be able to infer how to make a .y from an RCS file, as long as that
- XRCS file is in the RCS directory and has a name which ends in .y,v.
- XThe transitivity computation is performed dynamically for each target that
- Xdoes not have a recipe. This has potential to be very slow if the %-meta
- Xrules are not carefully specified. The .NOINFER attribute is used to mark
- Xa %-meta node as being a final target during inference. Any node with this
- Xattribute set will not be used for subsequent inferences. As an example
- Xthe node RCS/%,v is marked as a final node since we know that if the RCS file
- Xdoes not exist there likely is no other way to make it. Thus the standard
- Xstartup makefile contains the entry:
- X.RS
- X.nf
- X\&.NOINFER : RCS/%,v
- X.fi
- X.RE
- XThereby indicating that the RCS file is the end of the inference chain.
- X.PP
- X.B dmake
- Xtries to
- Xremove intermediate files resulting from transitive closure if the file
- Xis not marked as being PRECIOUS, or the \fB-u\fP flag was not given on the
- Xcommand line, and if the inferred intermediate did not previously exist.
- XIntermediate targets that existed prior to being made are never removed.
- XThis is in keeping with the philosophy that
- X.B dmake
- Xshould never remove things from the file system that it did not add.
- XIf the special target .REMOVE is defined and has a recipe then
- X.B dmake
- Xconstructs a list of the intermediate files to be removed and makes them
- Xprerequisites of .REMOVE. It then makes .REMOVE thereby removing the
- Xprerequisites if the recipe of .REMOVE says to. Typically .REMOVE is defined
- Xin the startup file as:
- X.sp
- X\t".REMOVE :; $(RM) $<".
- X.SH "MAKING TARGETS"
- XIn order to update a target \fBdmake\fP must execute a recipe.
- XWhen a recipe needs to be executed it is first expanded so that any macros
- Xin the recipe text are expanded, and it is then either executed directly or
- Xpassed to a shell.
- X.B dmake
- Xsupports two types of recipes. The regular recipes and group recipes.
- X.PP
- XWhen a regular recipe is invoked \fBdmake\fP executes each line of the recipe
- Xseparately using a new copy of a shell if a shell is required.
- XThus effects of commands do not generally persist across recipe lines.
- X(e.g. cd requests in a recipe line do not carry over to the next recipe line)
- XThe decision on whether a shell is required to execute a command is based on
- Xthe value of the macro SHELLMETAS or on the specification of '+' or .USESHELL
- Xfor the current recipe or target respectively.
- XIf any character in the value of
- XSHELLMETAS is found in the expanded recipe text-line or the use of a shell
- Xis requested explicitly via '+' or .USESHELL then the command is
- Xexecuted using a shell, otherwise the command is executed directly.
- XThe shell that is used for execution is given by the value of the macro SHELL.
- XThe flags that are passed to the shell are given by the value of SHELLFLAGS.
- XThus \fBdmake\fP constructs the command line:
- X.sp
- X\t$(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
- X.sp
- XNormally
- X.B dmake
- Xwrites the command line that it is about to invoke to standard output.
- XIf the .SILENT attribute is set for the target or for
- Xthe recipe line (via @), then the recipe line is not echoed.
- X.PP
- XGroup recipe processing is similar to that of regular recipes, except that
- Xa shell is always invoked. The shell that is invoked is given by the value of
- Xthe macro GROUPSHELL, and its flags are taken from the value of the macro
- XGROUPFLAGS. If a target has the .PROLOG attribute set then
- X.B dmake
- Xprepends to the shell script the recipe associated with the special target
- X\&.GROUPPROLOG, and if the attribute .EPILOG is set as well, then the recipe
- Xassociated with the special target .GROUPEPILOG is appended to the script
- Xfile.
- XThis facility can be used to always prepend a common header and common trailer
- Xto group recipes.
- XGroup recipes are echoed to standard output just like standard recipes, but
- Xare enclosed by lines beginning with [ and ].
- X.SH "MAKING LIBRARIES"
- XLibraries are easy to maintain using \fBdmake\fP. A library is a file
- Xcontaining a collection of object files.
- XThus to make a library you simply specify it as a target with the .LIBRARY
- Xattribute set and specify its list of prerequisites. The prerequisites should
- Xbe the object members that are to go into the library. When
- X.B dmake
- Xmakes the library target it uses the .LIBRARY attribute to pass to the
- Xprerequisites the .LIBMEMBER attribute and the name of the library. This
- Xenables the file binding mechanism to look for the member in the library if an
- Xappropriate object file cannot be found. A small example best illustrates
- Xthis.
- X.RS
- X.nf
- X.sp
- Xmylib.a .LIBRARY : mem1.o mem2.o mem3.o
- X\trules for making library...
- X\t# remember to remove .o's when lib is made
- X.sp
- X# equivalent to: '%.o : %.c ; ...'
- X\&.c.o :; rules for making .o from .c say
- X.sp
- X.fi
- X.RE
- X.B dmake
- Xwill use the .c.o rule for making the library members if appropriate .c files
- Xcan be found using the search rules. NOTE: this is not specific in any way
- Xto C programs, they are simply used as an example.
- X.PP
- X.B dmake
- Xtries to handle the old library construct format in a sensible way.
- XThe construct
- X.I lib(member.o)
- Xis separated and the \fIlib\fP portion is declared
- Xas a library target.
- XThe new target is defined
- Xwith the .LIBRARY attribute set and the \fImember.o\fP portion of the
- Xconstruct is
- Xdeclared as a prerequisite of the lib target.
- XIf the construct \fIlib(member.o)\fP
- Xappears as a prerequisite of a target in the
- Xmakefile, that target has the new name of the lib assigned as it's
- Xprerequisite. Thus the following example:
- X.RS
- X.sp
- X.nf
- Xa.out : ml.a(a.o) ml.a(b.o); $(CC) -o $@ $<
- X
- X\&.c.o :; $(CC) -c $(CFLAGS) -o $@ $<
- X%.a:
- X\tar rv $@ $<
- X\tranlib $@
- X\trm -rf $<
- X.sp
- X.fi
- X.RE
- Xconstructs the following dependency
- Xgraph.
- X.RS
- X.sp
- X.nf
- Xa.out : ml.a; $(CC) -o $@ $<
- Xml.a .LIBRARY : a.o b.o
- X
- X%.o : %.c ; $(CC) -c $(CFLAGS) -o $@ $<
- X%.a :
- X\tar rv $@ $<
- X\tranlib $@
- X\trm -rf $<
- X.sp
- X.fi
- X.RE
- Xand making a.out then works as expected.
- X.PP
- XThe same thing happens for any target of the form \fIlib((entry))\fP.
- XThese targets have an
- Xadditional feature in that the \fIentry\fP target has the .SYMBOL attribute
- Xset automatically.
- X.PP
- XNOTE: If the notion of entry points is supported by the archive and by
- X\fBdmake\fP (currently not the case) then
- X.B dmake
- Xwill search the archive for the entry point and return not only the
- Xmodification time of the member which defines the entry but also the name of
- Xthe member file. This name will then replace \fIentry\fP and will be used for
- Xmaking the member file. Once bound to an archive member the .SYMBOL
- Xattribute is removed from the target.
- XThis feature is presently disabled as there is little standardization
- Xamong archive formats, and we have yet to find a makefile utilizing this
- Xfeature (possibly due to the fact that it is unimplemented in most versions
- Xof UNIX Make).
- X.SH "MULTI PROCESSING"
- XIf the architecture supports it then \fBdmake\fP is capable of making a target's
- Xprerequisites in parallel. \fBdmake\fP will make as much in parallel as it
- Xcan and use a number of child processes up to the maximum specified by
- XMAXPROCESS or by the value supplied to the -P command line flag.
- XA parallel make is enabled by setting the value of MAXPROCESS (either directly
- Xor via -P option) to a value which is > 1.
- X\fBdmake\fP guarantees that all dependencies as specified in the makefile are
- Xhonored. A target will not be made until all of its prerequisites have been
- Xmade.
- XIf a parallel make is being performed then the following restrictions on
- Xparallelism are enforced.
- X.RS
- X.IP 1.
- XIndividual recipe lines in a non-group recipe are performed sequentially in
- Xthe order in which they are specified within the makefile and in parallel with
- Xthe recipes of other targets.
- X.IP 2.
- XIf a target contains multiple recipe definitions (cf. :: rules) then these are
- Xperformed sequentially in the order in which the :: rules are specified within
- Xthe makefile and in parallel with the recipes of other targets.
- X.IP 3.
- XIf a target rule contains the `!' modifier, then the recipe is performed
- Xsequentially for the list of outdated prerequisites and in parallel with the
- Xrecipes of other targets.
- X.IP 4.
- XIf a target has the .SEQUENTIAL attribute set then all of its prerequisites
- Xare made sequentially relative to one another (as if MAXPROCESS=1), but in
- Xparallel with other targets in the makefile.
- X.RE
- X.PP
- XNote: If you specify a parallel make then
- Xthe order of target update and the order in which the associated recipes are
- Xinvoked will not correspond to that displayed by the -n flag.
- X.SH "CONDITIONALS"
- X.B dmake
- Xsupports a makefile construct called a \fIconditional\fR. It allows
- Xthe user
- Xto conditionally select portions of makefile text for input processing
- Xand to discard other portions. This becomes useful for
- Xwriting makefiles that are intended to function for more than one target
- Xhost and environment. The conditional expression is specified as follows:
- X.sp
- X.RS
- X.nf
- X\&.IF \fIexpression\fR
- X ... if text ...
- X\&.ELSE
- X ... else text ...
- X\&.END
- X.RE
- X.fi
- X.sp
- XThe .ELSE portion is optional, and the conditionals may be nested (ie.
- Xthe text may contain another conditional).
- X\&.IF, .ELSE, and .END
- Xmay appear anywhere in the makefile, but a single conditional expression
- Xmay not span multiple makefiles.
- X.PP
- X\fIexpression\fR can be one of the following three forms:
- X.sp
- X\t<text> | <text> == <text> | <text> != <text>
- X.sp
- Xwhere \fItext\fR is either text or a macro expression. In any case,
- Xbefore the comparison is made, the expression is expanded. The text
- Xportions are then selected and compared. White space at the start and
- Xend of the text portion is discarded before the comparison. This means
- Xthat a macro that evaluates to nothing but white space is considered a
- XNULL value for the purpose of the comparison.
- XIn the first case the expression evaluates TRUE if the text is not NULL
- Xotherwise it evaluates FALSE. The remaining two cases both evaluate the
- Xexpression on the basis of a string comparison.
- XIf a macro expression needs to be equated to a NULL string then compare it to
- Xthe value of the macro $(NULL).
- X.SH "EXAMPLES"
- X.RS
- X.nf
- X.sp
- X# A simple example showing how to use make
- X#
- Xprgm : a.o b.o
- X cc a.o b.o -o prgm
- Xa.o : a.c g.h
- X cc a.c -o $@
- Xb.o : b.c g.h
- X cc b.c -o $@
- X.fi
- X.RE
- X.sp
- XIn the previous
- Xexample prgm is remade only if a.o and/or b.o is out of date with
- Xrespect to prgm.
- XThese dependencies can be stated more concisely
- Xby using the inference rules defined in the standard startup file.
- XThe default rule for making .o's from .c's looks something like this:
- X.sp
- X\&\t%.o : %.c; cc -c $(CFLAGS) -o $@ $<
- X.sp
- XSince there exists a rule (defined in the startup file)
- Xfor making .o's from .c's
- X\fBdmake\fR will use that rule
- Xfor manufacturing a .o from a .c and we can specify our dependencies
- Xmore concisely.
- X.sp
- X.RS
- X.nf
- Xprgm : a.o b.o
- X cc -o prgm $<
- Xa.o b.o : g.h
- X.fi
- X.RE
- X.sp
- XA more general way to say the above using the new macro expansions
- Xwould be:
- X.sp
- X.RS
- X.nf
- XSRC = a b
- XOBJ = {$(SRC)}.o
- X.sp
- Xprgm : $(OBJ)
- X cc -o $@ $<
- X.sp
- X$(OBJ) : g.h
- X.fi
- X.RE
- X.sp
- XIf we want to keep the objects in a separate directory, called
- Xobjdir, then we would write
- Xsomething like this.
- X.sp
- X.RS
- X.nf
- XSRC = a b
- XOBJ = {$(SRC)}.o
- X.sp
- Xprgm : $(OBJ)
- X cc $< -o $@
- X.sp
- X$(OBJ) : g.h
- X\&%.o : %.c
- X $(CC) -c $(CFLAGS) -o $(@:f) $<
- X mv $(@:f) objdir
- X
- X\&.SOURCE.o : objdir # tell make to look here for .o's
- X.fi
- X.RE
- X.sp
- XAn example of building library members would go something like this:
- X(NOTE: The same rules as above will be used to produce .o's from .c's)
- X.sp
- X.RS
- X.nf
- XSRC\t= a b
- XLIB\t= lib
- XLIBm\t= { $(SRC) }.o
- X.sp
- Xprgm: $(LIB)
- X cc -o $@ $(LIB)
- X.sp
- X$(LIB) .LIBRARY : $(LIBm)
- X ar rv $@ $<
- X rm $<
- X.fi
- X.RE
- X.sp
- XFinally, suppose that each of the source files in the previous example had
- Xthe `:' character in their target name. Then we would write the above example
- Xas:
- X.sp
- X.RS
- X.nf
- XSRC\t= f:a f:b
- XLIB\t= lib
- XLIBm\t= "{ $(SRC) }.o" # put quotes around each token
- X.sp
- Xprgm: $(LIB)
- X cc -o $@ $(LIB)
- X.sp
- X$(LIB) .LIBRARY : $(LIBm)
- X ar rv $@ $<
- X rm $<
- X.fi
- X.RE
- X.SH "COMPATIBILITY"
- XThere are two notable differences between
- X.B \fBdmake\fR
- Xand the standard version of BSD UNIX 4.2/4.3 Make.
- X.RS
- X.IP 1. .3i
- XBSD UNIX 4.2/4.3 Make supports wild card filename expansion for
- Xprerequisite names. Thus if a directory contains a.h, b.h and c.h, then a
- Xline like
- X.sp
- X\ttarget: *.h
- X.sp
- Xwill cause UNIX make to expand the *.h into "a.h b.h c.h". \fBdmake\fR
- Xdoes not support this type of filename expansion.
- X.IP 2. .3i
- XUnlike UNIX make, touching a library member causes \fBdmake\fR
- Xto search the library for the member name and to update the library time stamp.
- XThis is only implemented in the UNIX version.
- XMSDOS and other versions may not have librarians that keep file time stamps,
- Xas a result \fBdmake\fR touches the library file itself, and prints a warning.
- X.RE
- X.PP
- X\fBdmake\fP is not compatible with GNU Make. In particular it does not
- Xunderstand GNU Make's macro expansions that query the file system.
- X.PP
- X.B dmake
- Xis fully compatible with SYSV AUGMAKE, and supports the following AUGMAKE
- Xfeatures:
- X.RS
- X.IP 1. .3i
- XThe word \fBinclude\fP appearing at the start of a line can be used instead of
- Xthe ".INCLUDE :" construct understood by \fBdmake\fP.
- X.IP 2. .3i
- XThe macro modifier expression $(macro:str=sub) is understood and is equivalent
- Xto the expression $(macro:s/str/sub), with the restriction that str must match
- Xthe following regular expression:
- X.sp
- X\tstr[ |\\t][ |\\t]*
- X.sp
- X(ie. str only matches at the end of a token where str is a suffix and is
- Xterminated by a space, a tab, or end of line)
- X.IP 3.
- XThe macro % is defined to be $@ (ie. $% expands to the same value as $@).
- X.IP 4.
- XThe AUGMAKE notion of libraries is handled correctly.
- X.IP 5.
- XWhen defining special targets for the inference rules and the AUGMAKE special
- Xtarget mapping is enabled then the special target
- X\&.X is equivalent to the %-rule "% : %.X".
- X.RE
- X.SH "LIMITS"
- XIn some environments the length of an argument string is restricted.
- X(e.g. MSDOS command line arguments cannot be longer than 128 bytes if you are
- Xusing the standard command.com command interpreter as your shell,
- X.B dmake
- Xtext diversions may help in these situations.)
- X.SH "PORTABILITY"
- XTo write makefiles that can be moved from one environment to another requires
- Xsome forethought. In particular you must define as macros all those things
- Xthat may be different in the new environment.
- X.B dmake
- Xhas two facilities that help to support writing portable makefiles, recursive
- Xmacros and conditional expressions. The recursive macros, allow one to define
- Xenvironment configurations that allow different environments for similar types
- Xof operating systems. For example the same make script can be used for SYSV and
- XBSD but with different macro definitions.
- X.PP
- XTo write a makefile that is portable between UNIX and MSDOS requires both
- Xfeatures since in almost all cases you will need to define new recipes for
- Xmaking targets. The recipes will probably be quite different since the
- Xcapabilities of the tools on each machine are different. Different
- Xmacros will be needed to help handle the smaller differences in the two
- Xenvironments.
- X.PP
- XNOTE: Unlike UNIX, MSDOS \fBdoes\fP maintain cd requests
- Xcross single recipe lines.
- XThis is not portable, and your makefiles will not work the same way if you
- Xdepend on it. Use the .IF ... .ELSE ... .END conditionals to supply different
- Xmake scripts as necessary.
- X.SH FILES
- XMakefile, makefile, startup.mk (use dmake -V to tell you where the startup
- Xfile is)
- X.SH "SEE ALSO"
- Xsh(1), csh(1), touch(1), f77(1), pc(1), cc(1)
- X.br
- XS.I. Feldman \fIMake - A Program for Maintaining Computer Programs\fP
- X.SH "AUTHOR"
- XDennis Vadura, CS Dept. University of Waterloo. dvadura@watdragon.uwaterloo.ca
- X.br
- XMany thanks to Carl Seger for his helpful suggestions,
- Xand to Trevor John Thompson for his many excellent ideas and
- Xinformative bug reports.
- X.SH BUGS
- XSome system commands return non-zero status inappropriately.
- XUse
- X.B \-i
- X(`\-' within the makefile) to overcome the difficulty.
- X.PP
- XSome systems do not have easily accessible
- Xtime stamps for library members (MSDOS, AMIGA, etc)
- Xfor these \fBdmake\fR uses the time stamp of the library instead and prints
- Xa warning the first time it does so. This is almost always ok, except when
- Xmultiple makefiles update a single library file. In these instances it is
- Xpossible to miss an update if one is not careful.
- SHAR_EOF
- echo "File man/dmake.tf is complete"
- chmod 0440 man/dmake.tf || echo "restore of man/dmake.tf fails"
- echo "x - extracting man/dmake.p (Text)"
- sed 's/^X//' << 'SHAR_EOF' > man/dmake.p &&
- X
- X
- X
- X
- XDMAKE(p) Unsupported Software DMAKE(p)
- X
- X
- X
- XNNAAMMEE
- X ddmmaakkee - maintain program groups, or interdependent files
- X
- XSSYYNNOOPPSSIISS
- X ddmmaakkee [-AeEhiknpqersStTuvVx] [-P#] [macro[*][+][:]=_v_a_l_u_e]
- X [-f file] [target ...]
- X
- XDDEESSCCRRIIPPTTIIOONN
- X ddmmaakkee executes commands found in an external file called a
- X _m_a_k_e_f_i_l_e to update one or more target names. Each target
- X may depend on zero or more prerequisite targets. If any of
- X the target's prerequisites is newer than the target or if
- X the target itself does not exist, then ddmmaakkee will attempt to
- X make the target.
- X
- X If no --ff command line option is present then ddmmaakkee searches
- X for an existing _m_a_k_e_f_i_l_e from the list of prerequisites
- X specified for the special target _._M_A_K_E_F_I_L_E_S (see the STARTUP
- X section for more details). If "-" is the name of the file
- X specified to the --ff flag then ddmmaakkee uses standard input as
- X the source of the makefile text.
- X
- X Any macro definitions (arguments with embedded "=" signs)
- X that appear on the command line are processed first and
- X supercede definitions for macros of the same name found
- X within the makefile. In general it is impossible for defin-
- X itions found inside the makefile to redefine a macro defined
- X on the command line, see the MACROS section for an excep-
- X tion.
- X
- X If no _t_a_r_g_e_t names are specified on the command line, then
- X ddmmaakkee uses the first non-special target found in the
- X makefile as the default target. See the SSPPEECCIIAALL TTAARRGGEETTSS
- X section for the list of special targets and their function.
- X ddmmaakkee is a re-implementation of the UNIX Make utility with
- X significant enhancements. Makefiles written for most previ-
- X ous versions of _m_a_k_e will be handled correctly by ddmmaakkee..
- X Known differences between ddmmaakkee and other versions of make
- X are discussed in the CCOOMMPPAATTIIBBIILLIITTYY section found at the end
- X of this document.
- X
- XOOPPTTIIOONNSS
- X --AA Enable AUGMAKE special inference rule transformations
- X (see the "PERCENT(%) RULES" section), these are set to
- X off by default.
- SHAR_EOF
- echo "End of part 12"
- echo "File man/dmake.p is continued in part 13"
- echo "13" > s2_seq_.tmp
- exit 0
-
-